<!DOCTYPE html>
<html>
<head>
<title>Elda reference</title>
<link href="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css" rel="stylesheet" />
<link href="../style.css" rel="stylesheet" />
<script src="../util.js"></script>
</head>

<body onload="toc()">
<nav class="navbar navbar-default" role="navigation">
  <div class="navbar-header">
    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-ex1-collapse">
      <span class="sr-only">Toggle navigation</span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <div class="navbar-brand">
      <h1 class="not-toc">Elda 1.2.28</h1>
      <h2 class="not-toc">An implementation of the linked-data API</h2>
    </div>
  </div>

  <!-- Collect the nav links, forms, and other content for toggling -->
  <div class="collapse navbar-collapse navbar-ex1-collapse">
    <ul class="nav navbar-nav">
      <li class=""><a href="index.html">Quick start</a></li>
      <li class="active"><a href="reference.html">Reference</a></li>
      <li class=""><a href="cribsheet.html">Crib sheet</a></li>
      <li class=""><a href="search-example.html">Text search example</a></li>
      <li class=""><a href="velocity.html">Velocity renderer</a></li>
    </ul>
    <div class="nav navbar-nav navbar-right">
      <img class="logo" src="../epilogo-240.png" alt="Epimorphics.com">
    </div>
  </div><!-- /.navbar-collapse -->
</nav>


<div class="container">
<div class="main">

<div id="toc" class="well pull-right">
<h2 class="not-toc">Table of contents</h2>
</div>

<h1 id="elda-common">Elda Common</h1>

<p>
	The stand-alone jar serves as a demonstration tool
	and small-scale Elda service. However, the preferred
	way of delivering an externally-viewed scalable
	Elda service is to use Elda Common (or write your
	own webapp based on the Elda artifacts, or course).
</p>

<p>
	Elda Common provides a way of dropping Elda
	into an existing webapp container with a minimum of fuss.
	(While we write "Tomcat" below as the webapp container,
	any suitably configurable one &mdash; <em>eg</em> Jetty
	&mdash; will do. We assume that you have the necessary
	access permissions to install or update Tomcat and
	run it on your preferred port.)
</p>

<p>
There are three components to Elda Common:
</p>
<ul>
	<li>
		The Elda Common War, a Maven artifact you can download
		in the usual way as file
		<code>elda-common-VERSION.war</code>.
	</li>

	<li>
		The Elda Assets War, a Maven artifact you can download
		in the usual way as <code>elda-assets-VERSION.war</code>.
	</li>

	<li>
		<a href="http://elda.googlecode.com/hg/elda-assets/src/main/webapp/specs/ROOT_minimal.ttl">
		Minimal LDA configurations</a> demonstrating Elda Common setup.
	</li>
</ul>

<p>
The Common and Assets files must have the same version.
</p>

<p>
	To use Elda Common, you add both .war files to your Tomcat
	configuration. Doing so may be as simple as dropping them
	into the appropriate <code>webapps</code> directory.
	You need both .war files;
	Elda Common contains the LDA-handling Java code and Elda
	Assets provides styleheets, scripts, css, <em>etc</em> which Elda
	Common refers to or loads. There is also an
	<code>elda-bundled</code>
	artifact whose <code>elda-bundled.war</code> combines
	<code>elda-common</code> and <code>elda-assets</code> into one item.
</p>

<p>
	By default, Elda Common assumes that Elda Common's context
	path is <code>elda-common</code> and Elda Assets's context
	path is <code>elda-assets</code>. If you want them to use
	different context paths, you will need to also change the
	name and contents of the LDA config (see below). You can
	install multiple copies of Elda Common with different
	context paths, all sharing the same assets. (You can also
	have multiple different assets if necessary.) You can
	install Elda as ROOT.war so that Tomcat is serving the
	URI templates with no prefix, so long as the name of the
	assets .war does not collide with any of those templates.
</p>

<p>
	Elda Common loads its LDA configurations from
	<code>/etc/elda/conf.d/{APP}/*.ttl</code>, where
	<code>{APP}</code> is the context path of that instance
	of Elda Common. This means that each instance may have
	multiple configs that it can load, and different instances
	can load different files. (See the <code>web.xml</code>
	for the setting of this configuration path.)
</p>

<p>
	The LDA configurations contain references to the assets
	webapp, as seen in the minimal configuration file
	supplied. For a given <code>API:api</code> in a configuration file,
	the location of the assets is given in a variable
	binding:
</p>

<pre>
; api:variable [api:name "_resourceRoot"; api:value "http://<em>hostAndPort</em>/<em>assetPath</em>/"]
</pre>

<p>
	The <em>hostAndPort</em> will usually be <strong>localhost:8080</strong>
	or <strong>localhost:80</strong>, and <em>assetPath</em> will by default
	be <strong>elda-assets</strong> unless the asset .war is renamed to some
	other context or you are using <code>elda-bundled</code>.
</p>

<p>
	Similarly, if the configuration is generating HTML using the
	Elda XSLT renderer, the stylesheets are loaded from the
	assets according to the binding on the XsltFormatter by:
</p>

<pre>
; api:stylesheet "http://<em>hostAndPort</em>/<em>stylesheetPath</em>/xslt/result.xsl"
</pre>

<p>
	Again, if the stylesheet has moved, this binding must be
	changed accordingly.
</p>

<p>
	Elda provides several example minimal configurations, different
	only in their intended environments:
</p>

<table class="table table-striped table-condensed">
<tr>
  <td><a href="specs-1.2.28/minimal-named-bundled-8080-config.ttl">minimal-named-bundled-8080-config.ttl</a></td>
  <td>bundled non-ROOT configuration running on port 8080.</td>
</tr>

<tr>
  <td><a href="specs-1.2.28/minimal-named-or-ROOT-split-8080-config.ttl">minimal-named-or-ROOT-split-8080-config.ttl</a></td>
  <td>split assets and common on port 8080, for both ROOT and non-ROOT use.</td>
</tr>

<tr>
  <td><a href="specs-1.2.28/minimal-named-split-80-config.ttl">minimal-named-split-80-config.ttl</a></td>
  <td>split assets and common on port 80 for non-ROOT use.</td>
</tr>

<tr>
  <td><a href="specs-1.2.28/minimal-ROOT-bundled-8080-config.ttl">minimal-ROOT-bundled-8080-config.ttl</a></td>
  <td>ROOT bundled and running on port 8080.</td>
</tr>

</table>


<p>
	The configuration itself is a place-holder with
	three uri templates:
</p>

<table class="table table-striped table-condensed">
  <tr>
    <td><code>/anything</code></td>
    <td>to provide some example results</td>
  </tr>
  <tr>
    <td><code>/about?resource={someURI}</code></td>
    <td>provides information (ie properties and their values) about the
      resource <code>someURI</code></td>
  </tr>
  <tr>
    <td><code>/mentions?resource={someURI}</code></td>
    <td>finds items which have <code>someURI</code> as the value of some property.</td>
  </tr>

</table>

<p>
	The minimal configuration assumes that a SPARQL endpoint is
	available on <code>localhost:3030/store</code>. You can
	replace this endpoint with a different one, or for development
	purposes you can run a <a href="http://jena.apache.org/documentation/serving_data/">Fuseki</a>
	SPARQL server serving RDF data of your choice.
</p>

<h2>Reload on change</h2>

<p>
	When Elda handles a request, if it has been "sufficiently
	long" since the last request, it will check to see if it
	is up-to-date with its configuration and, if not, reload it.
</p>

<p>
	"Sufficently long" defaults to 5 seconds and can be adjusted
	by creating the file <code>/etc/elda/conf.d/{APP}/delay.int</code>.
	<code>APP</code> is the context path for this Elda webapp. The
	content of the file must be an integer number of millseconds.
</p>

<p>
	"Up-to-date" means that none of the configuration files or their
	directories are time-stamped later than the time that the
	configurations were loaded.
</p>

<p>
	Elda does not check that the <em>contexts</em> of these files
	have changed, so it is sufficient to simple <code>touch</code>
	one of the appropriate files.
</p>

<h2>Inside Elda Common</h2>

<p>
	To use Elda for your own webapps, you can use Elda Common
	(suitably replacing the minimal LDA config), produce your
	own merge of Common and Assets, or tweak the Elda Standalone
	warfile. You will need to edit the web.xml appropriately.
</p>

<p>
	If you have downloaded the Elda repository, then you can
	rebuild the Elda working jar (lda-VERSION.jar)
	and webapp using <a href="http://maven.apache.org/">Maven</a>;
	see below.
</p>

<h2 id="anatomy">Anatomy of Elda's web.xml</h2>

<p>
	Elda runs as a bunch of JAX-RS resources within a Jersey
	container. The LDA configurations it loads are specified
	by the value of a <em>context parameter</em>.
</p>

<pre>
&lt;context-param>
   &lt;param-name>com.epimorphics.api.initialSpecFile&lt;/param-name>
   &lt;param-value>/etc/elda/conf.d/{APP}/*.ttl&lt;/param-value>
&lt;/context-param>
</pre>

<p>
	For non-Common uses of Elda, you can have multiple comma-separated
	configuration directives in a single &lt;param-value&gt;. Spaces, tabs,
	and newlines within the value are discarded.
</p>

<p>
	Each directive is a filename, with an optional leading
	prefix specification consisting of a name followed by
	<code>::</code>.
</p>

<p>
	If the prefix is supplied, then all of the URI templates
	in the configuration are implicitly prefixed with it;
	this allows different configurations to be loaded together
	even if they happen to share URI templates.
</p>

<p>
	The provided filename is a webapp-relative unless it starts
	with "/". Any occurence of the string "{APP}" is replaced
	by the context path, and the character "*" matches any sequence
	of characters, allowing multiple configuration files to be
	specified at one time and appropriately to this webapp.
</p>

<p>
	The string <code>{file}</code> in the prefix is replaced
	by the base of the filename with any trailing <code>.ttl</code>
	removed. The string <code>{api}</code> in the prefix is replaced
	by the local name(s) of the API resouce(s) in the spec.
</p>

<p>
	If the prefix contains a '*' character, it is replaced by whatever
	characters matched any wildcard '*'s in the last segment of the
	filename. (If there is more than one such '*', the matching groups
</p>

<h4>Example</h4>

<p>
	Given the directive <code>A*B::/etc/elda/*.ttl</code> and
	files <code>x.ttl</code>, <code>y.ttl</code> and <code>z.text</code>
	in <code>/etc/elda</code>, the configuration file <code>x.ttl</code>
	will be loaded and given prefix <code>AxB</code> and the
	file <code>y.ttl</code> will be loaded with prefix <code>AyB</code>.
	<code>z.text</code> is ignored as it does not match the filename.
</p>

<h2 id="servlet">The Jersey servlet/filter</h2>

<p>
	Elda runs Jersey either as a servlet or as a filter applied to
	all of the paths for this context path. A path that does not
	match any LDA  URI template produces a NOT FOUND status that
	by default is handled by Tomcat to serve a static file if one exists
	with that pathname. JAX RS resources are located in the
	package <code>com.epimorphics.lda.restlets</code>.
</p>

<pre>
 &lt;filter&gt;
    &lt;filter-name&gt;Jersey Web Application&lt;/filter-name&gt;
    &lt;filter-class&gt;com.sun.jersey.spi.container.servlet.ServletContainer&lt;/filter-class&gt;

    &lt;init-param&gt;
      &lt;param-name&gt;com.sun.jersey.config.property.packages&lt;/param-name&gt;
	  &lt;param-value&gt;<strong>com.epimorphics.lda.restlets</strong>&lt;/param-value&gt;
    &lt;/init-param&gt;

    &lt;init-param&gt;
	  &lt;param-name&gt;com.sun.jersey.config.feature.<strong>FilterForwardOn404</strong>&lt;/param-name&gt;
	  &lt;param-value&gt;<strong>true</strong>&lt;/param-value&gt;
    &lt;/init-param&gt;

    &lt;init-param&gt;
         &lt;param-name&gt;com.sun.jersey.spi.container.ContainerRequestFilters&lt;/param-name&gt;
         &lt;param-value&gt;com.sun.jersey.api.container.filter.PostReplaceFilter&lt;/param-value&gt;
     &lt;/init-param&gt;
&lt;/filter&gt;

&lt;filter-mapping&gt;
    &lt;filter-name&gt;Jersey Web Application&lt;/filter-name&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;

&lt;servlet-mapping&gt;
    &lt;servlet-name&gt;default&lt;/servlet-name&gt;
    &lt;url-pattern&gt;&lt;b&gt;/*&lt;b&gt;&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;

&lt;listener&gt;
  &lt;listener-class>com.epimorphics.lda.restlets.RouterRestlet$Init&lt;/listener-class&gt;
&lt;/listener&gt;
</pre>

<p>
	The (optional) <code>Init</code> listener forces Elda to load its
	configurations when the webapp starts. If this listener is
	omitted, Elda will load configurations when the first request
	arrives.
</p>

<p>
	Everything else is handled by the default servlet, which
	delivers all the static files inside the webapp.
</p>

<h2 id="rewriting">URL rewriting</h2>

<p>
	Elda Common does not do URL rewriting; it handles all of the
	requests sent to its context, either as URI templates or
	as static files. For applications that need to present
	different URIs to an external interface from those used within
	the application, you can either use on of the existing
	within-servlet URI rewriting engines or having a front-end
	server, <em>eg</em> Apache or Nginx, which selectively rewrites
	or discards requests with (un)suitable URIs.
</p>

<h4 id="loading-config">Obsolete: the Loader servlet</h4>

<p>
	Previous versions of Elda had their configuration specified
	within a load-on-startup Loader servlet with an init-param
	<code>initialSpecFile</code> supplying the configuration file names.
	This approach to configuration is now <em>obsolete</em> as it lead
	to technical difficulties; it is supported in Elda 1.2.28 to
	allow users to migrate to the new configuration process.
</p>

<h1>Velocity template rendering</h1>

<p>
    This release of Elda includes the ability to use
    <a href="http://velocity.apache.org/">Velocity</a>
    templates for rendering. This feature is <em>provisional</em>;
    it may change significantly in future releases.
</p>

<p>
    To use the Velocity renderer to generate HTML, attach this formatter to
    your API spec:
</p>

<pre>
&lt;yourSpec> api:defaultFormatter
	[a elda:VelocityFormatter
	; api:name "vhtml"
	; elda:className "com.epimorphics.lda.renderers.VelocityRendererFactory"
	; api:mimeType "text/html"
	]
</pre>

<p>
    By default, this will render the template
    <code>page-shell.vm</code> found in <code>{_velocityRoot}</code>
    if <code>_velocityRoot</code> is defined, or in
    <code>{_resourceRoot/vm}</code> otherwise. (<code>_resourceRoot</code>
    has a default value.) The provided template generates HTML in a style
    modelled after that of the default HTML rendering performed by
    XSLT stylesheets. Note the renderer name (and hence its format-selection
    suffix) is "vhtml" not "html" to allow the two different HTML renderers
    to operate on the same Elda endpoint. 
</p>

<p>
	See <a href="velocity.html">velocity.html</a> for more about the
	Elda interface to Velocity.
</p>

<h1 id="text-search">Free-text searching</h1>

<p>
	Normally, specifying a query parameter <code>sn=v</code>
	to Elda (or using the equivalent <code>api:filter</code>
	in the configuration file) requires that for an item
	to be selected, it must have a value for the property
	whose short-name is <code>sn</code> and whose value is
	<code>v</code>. This allows you, for example, to find
	an item whose rdfs:label is "hello there" by using the
	query parameter <code>label=hello%20there</code>,
	assuming <code>label</code> is the short-name of
	<code>rdfs:label</code>.
</p>

<p>
	However, if you want to find items whose (<em>eg</em>)
	<code>rdfs:label</code> text <em>contains</em> <strong>hello</strong>,
	or which contains either <strong>hello</strong> OR <strong>goodbye</strong>,
	<em>etc</em>, then you have to write explicit SPARQL
	<code>FILTER</code>s, probably using regular expressions,
	and smuggle them into your configuration. This works, and
	is very flexible, but is also rather inefficient, since
	<em>all</em> the literal values of the desired property have
	to be examined, and general regular expressions are quite
	complicated to process.
</p>

<p>
	One solution to this is <em>indexing</em>. The literal text
	value of the RDF properties is preprocessed, typically by
	breaking it up into words, and an index constructed relating
	each word to all the literals it appears in. Then a search
	string can likewise be broken up into words and the search limited
	to literals that are related to those words. This can be
	made much faster than a scan-and-regexp -- indexing can be
	done in advance and updated incrementally as new RDF is
	added to the dataset.
</p>

<p>
	Two related examples of text indexing and search are
	<a href="http://lucene.apache.org/core/">Apache Lucene</a>
	and <a href="http://lucene.apache.org/solr/">Apache Solr</a>.
	Recent <a href="http://jena.apache.org/documentation/serving_data/">
	Jena Fuseki</a> SPARQL servers offer an abtraction layer over
	these text search engines, and Elda can exploit this. A
	special property (usually called <code>text:query</code>)
	matches literals using the text engine rather than RDF
	literal lookup.
</p>

<p>
	If the query parameter <code>_search</code> is defined,
	Elda uses its value as the search string for the
	<code>text:query</code> property. The configuration
	file can specify further details of how this transformation
	is performed. If the SPARQL endpoint understands the
	<code>text:query</code> property (it need not be a
	Fuseki, so long as it understands the same protocol),
	then the text search engine will handle the query.
</p>

<p>
	Using text search is a three-step process; deciding what properties
	are to be indexed under what names; building (for the server) the
	index; and using <code>_search</code> to make a query against that
	index.
</p>

<p>
	We sketch these three steps below, but for details of the indexing
	and query operations, see the references search/Lucene/Solr references
	above. <a href="search-example.html">Another document</a>
	provides a worked example of creating a simple text-search-enabled Elda.
	See <a href="http://jena.apache.org/documentation/query/text-query.html">
	Text searches with SPARQL</a> for more about the text-query module.
</p>

<h2>Dataset indexing</h2>

<p>
	A Fuseki dataset can be configured to <em>index</em> specified properties
	within an RDF model. The properties are associated with named
	<em>fields</em> in the index. One of these fields can be designated
	as the <em>default</em> field, the field that is searched if no
	field is explicitly given in a search query; another can be designated
	as the <em>uri</em> field that holds the URI of the resource associated
	with the search strings. For example, the configuration in the Jena
	text search documentation makes the default field name <em>text</em>,
	has it track the value of the property <em>rdfs:label</em>, and binds the
	URI of the item to the field <em>uri</em>:
</p>

<pre>
...
&lt;#entMap&gt; a text:EntityMap ;
    text:entityField      "uri" ;
    text:defaultField     "text" ;
    text:map (
         [ text:field "text" ; text:predicate rdfs:label ]
         ) .
...
</pre>

<p>
	The indexing process breaks the text (of the objects of the
	properties) into words and discards unhelpful terms such as "a" and
	"the" because they do not discriminate well. It may -- depending on
	details of the Lucene/Solr configuration -- do stemming and synonym
	indexing as well. These words are the terms that can be used in the
	search.
</p>

<h2>Text query</h2>

<p>
	The value of the <code>_search</code> query parameter is passed
	through to Fuseki and used as a <em>query</em> against the index.
	Just as the indexing operates on text that has been broken up
	into words, the query isn't just a string to search for: it is
	expressed in it own little language, as defined by Lucene and
	very similarly by Solr (the Solr query language is mostly a modest
	extension to the Lucene language). The simplest query is a single
	word, eg <em>Steam</em> or <em>Mahal</em>, which will succeed for
	resources that have that word in one of their property values.
</p>

<blockquote>
	(The indexing/query process may work harder than this for match,
	eg by looking for stems or synonyns of words, but these details are
	endpoint and implementation specific.)
</blockquote>

<p>
	The query can contain several words; if so, it is looking for <em>any</em>
	of those words. To force it to look for both, use the infix operator
	<em>AND</em>, which you can also spell <em>&amp;&amp;</em>. The query
	<em>Age Steam</em> will find resources that mention either of <em>Age</em>
	or <em>Steam</em>; the query <em>Age &amp;&amp; Steam</em> will find only
	resources that mention them both. Note that if you use the &amp;&amp;
	syntax in a URI it will have to be carefully escaped, so <em>AND</em>
	is probably the better choice.
</p>

<p>
	Prefxing a word with <em>+</em> demands that it appear <em>somewhere</em>
	in the indexed text (ie, the RDF model or any extra indexing text that
	the endpoint applied). Prefixing the word with <em>-</em> demands
	that it does <em>not</em> appear.
</p>

<p>
	The query runs against the default field unless otherwise specified
	using a <em>fieldName:</em> prefix. This prefix applies to the next
	(as short as possible) piece of the query, so <em>alpha: Age Steam</em>
	looks for <em>Age</em> in the <em>alpha</em> field and <em>Steam</em> in
	the default field. To make it apply to both terms, you can either
	repeat the field, <em>alpha: Age alpha: Steam</em>, or use parentheses
	for grouping, <em>alpha: (Age Stream)</em>. (You can also use
	parentheses in the usual way for grouping mixtures of <code>AND</code>
	and <code>OR</code>, etc.)
</p>

<p>	The query notation supports several other operators, and escapes so that
	operators like <em>+</em> can be treated as ordinatry characters; for
	information about these see eg
	<a href="http://lucene.apache.org/core/4_4_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description">the Lucene classic package summary</a>.
</p>

<h2>Configuring search</h2>

<p>
	The default behaviour of <code>_search</code> is that its value
	is used as a query against the Fuseki index of the SPARQL endpoint.
	If the value does not specify otherwise, the search is performed
	against the default field. The property that this is derived from
	is defined when the text is indexed.
</p>

<p>
	<code>_search</code>'s behaviour can be configured by properties
	attached to the SPARQL endpoint, the api:API itself (over-riding
	those on the SPARQL endpoint), or on individual API endpoints
	(over-riding the API and SPARQL endpoint). The most general
	way to do this is to use:
</p>

<pre>
<code>:APIorEndpoint elda:textSearchOperand</code> (... "?_search" ...)
</pre>


<p>
	The elements of the list can be an integer <code>N</code>, a resource
	<code>P</code> which should be the name of a property, a literal
	string <code>L</code>, or the special literal string <code>?_search</code>.
</p>

<ul>
<li>
	<code>N</code>. This restricts the number of results matched by the
	text search to <code>N</code>. If omitted, there is no restriction.
</li>

<li><code>P.</code>
	The search is performed with the default field being the field
	that is associated with <code>P</code> in the index.
</li>

<li><code>L.</code>
	The value of <code>_search</code> is ignored and <code>L</code>'s
	lexical form is used as the search query.
</li>

<li><code>"?_search".</code>
	This is replaced by the value of <code>_search</code> and
	will be used as the search query.
</li>
</ul>

<p>
	Rather than using this most general mechanism, specifying
</p>

<pre>
<code>:APIorEndpoint elda:textContentProperty some:Property</code>
</pre>

<p>
	will make the default field be that associated with
	<code>some:Property</code> in the same way as <code>P</code>
	in the general form above.
</p>

<p>
	It is also possible (but not expected) to be able to change
	the property used for text query by setting
</p>

<pre>
<code>elda:textQueryProperty some:Property</code>
</pre>

<p>
	By default, the <code>?item text:query literal</code> triples
	in the generated SPARQL query are positioned first. If you have
	reason to believe that your text search queries will be processed
	more efficiently by positioning them later (just before the
	type triples), then setting
</p>

<pre>
	elda:textPlaceEarly false
</pre>

<p>
	in the configuration will do so. Setting it <code>true</code> is
	equivalent to the default of setting it early. (This assumes that
	the SPARQL processor won't rearrange the query arbitrarily.)
</p>


<h2>search with shortnames</h2>

<p>
	Another way to use text search is to give <code>text:query</code>
	a shortname:
</p>

<pre>
text:query a rdf:Property
	; api:label "search"
	.
</pre>

<p>
	Because <code>text:query</code> can accept a simple string
	object, this allows a filter <code>search=something</code> to
	be used in the URL query parameters or in an <code>api:filter</code>
	in the configuration file. This is especially useful when the
	shortname appears at the end of a property chain such as
	<code>author.search=mckillip</code>.
</p>

<h2>Caveats</h2>

<p>
	This feature is experimental and details may change.
</p>

<p>
	The details of the query language -- and hence the meaning
	of the value of the _search query parameter -- may change
	between versions of Lucene and Solr. These versions are
	dictated by the builder of the SPARQL endpoint.
</p>

<h1>Query size control</h1>

<p>
	Some generated queries -- those that have view defined by
    property chains and are applied to many selected items --
    are rather large (exceeding a megabyte). These queries are
    repetitions of the view property accesses specialised by
    the selected item.
</p>

<h2 id="sparql-1.1-features">SPARQL 1.1 features</h2>

<p>
If the SPARQL server supports nested
    selects (part of, but not limited to, SPARQL 1.1), then
    these repetitions can be replaced by a single application
    of the view wrapped round a nested select that fetches
    the items.
</p>

<p>
    Elda automatically uses nested selects if the data source
    is a <strong>local:</strong> or <strong>tdb:</strong> model, or it the
    <code>sparqEndpoint</code> value of the API is a
    resource with an <strong>extras:supportsNestedSelects</strong>
    value of true, "true", or "yes". (We anticipate that
    later versions of Elda will dynamically check the server
    to see if nested selects work.)
</p>

<h2 id="describe-thresholds">DESCRIBE thresholds</h2>

<p>
    Support for nested selects applies to DESCRIBE queries as well,
    which may consist of a great many URIs when the selection
    phase generates many items. To give greater control over
    the use of nested selects for DESCRIBE, a view may be defined
    with the property <code>extras:describeThreshold</code>. This
    makes that view a DESCRIBE view on which nested selects
    (if available) are then only used if the number of selected
    items exceeds the value of this property.
</p>

<p>
    The default default threshold value is 10. However, it can be
    changed. Setting the <code>extras:describeThreshold</code>
    property on an <em>endpoint</em> makes all the (describe) viewers
    created for that endpoint have that value for their threshold.
    Setting that property on an <code>api:API</code> makes the
    default for all its endpoints be that value.
</p>

<p>
    (Values and defaulting rules may change in later releases
    of Elda according to reported experience.)
</p>


<h1 id="additional-elda-features">Additional Elda features</h1>

<h2 id="variables">Configuration variables</h2>

<p>
    Elda reserves LDA variable names that begin "_" for
    configuration purposes.
</p>

<p>
    While the LDA spec says
    (<a href="http://code.google.com/p/linked-data-api/wiki/API_Binding_Variables">see API Binding Variables</a>)    that:
</p>
    <blockquote>
	endpoint-level variables can also depend on API-level 
	variables, but not vice versa.
    </blockquote>
<p>
    Elda specifically allows API-level variables to depend on
    endpoint variables. This means that the value of an API
    variable cannot be determined in advance (if it depends on
    any variables that may be bound in endpoints, <em>eg</em>
    by appearing in a URI template). This turns out to allow
    convenient idioms where API-level variable declarations
    assemble a result from components that can appear elsewhere
    at the API level or from the current endpoint.
</p>

<h2>Configuring Elda resource paths</h2>

<p>
	There are three resource paths that you may need to configure
	for Elda: the <em>stylesheet path</em>, the <em>asset path</em>,
	and the <em>template path</em>.
</p>

<h3>stylesheet path</h3>

<p>
	The <em>stylesheet path</em> is used by the XSLT-driven HTML 
	renderer to locate the XSLT stylesheet to use. It appears as
	the object of an <code>api:stylesheet</code> property on the
	HTML renderer, <em>eg</em>
</p>

<pre>
... api:stylesheet "lda-assets/xslt/result-osm-trimmed.xsl"
</pre>

<p>
	If there are any variable references in the stylesheet
	value, they are expanded. If the resulting stylesheet value 
	starts with a scheme (<em>eg</em> <code>http:</code>) 
	then it is treated as the URL of the stylesheet to fetch.
	Otherwise it is treated as a reference to a file in the
	application's <code>webapp</code> directory.
</p>

<h3>asset path and <code>api:base</code></h3>

<p>
	The <em>asset path</em> is used by the (default) XSLT-driven 
	HTML renderer and the (default) velocity template renderer.
	It is the value of the LDA variable <code>_resourceRoot</code>:
</p>

<pre>
... api:variable [api:name "_resourceRoot"; api:value "lda-assets/"]
</pre>

<p>
	If that value is not defined, Elda uses the value of the <code>api:base</code>
	property of the API spec:
</p>

<pre>
... api:base "/"
</pre>

<p>
	<code>api:base</code> should, if possible, be used to specify where 
	the Elda webapp is served from; it is resolved against the URL 
	for the current page so that a server at location A can generate 
	URIs as though it were at location B.
</p>

<p>
	If <code>api:base</code> is not defined, Elda uses <code>"/lda-assets"</code>.
</p>

<p>
	When those renderers must generate a link in the HTML to some
	asset, such as an image or some CSS, the path to that asset
	(<em>eg</em>, <code>images/Star.png</code>) is prefixed with 
	the asset path (<em>eg</em>, <code>lda-assets/</code>) to
	construct the link URL (<em>eg</em>, <code>lda-assets/images/Star.png</code>).
	This URL will then be resolved in the usual way, relative
	to the URL of the page being rendered.  
</p>

<h3>template path</h3>

<p>
	The <em>template path</em> is used by the velocity template
	renderer to locate the templates it may expand. It is the value
	of the LDA variable <code>_velocityRoot</code>:
</p>

<pre>
... api:variable [api:name "_velocityRoot"; api:value "lda-assets/vm"]
</pre>

<p>
	Note that if the value is not an explict URI it is resolved <em>locally</em>
	(the same way as <code>api>stylesheet</code>) against the webapp
	directory, as opposed to <code>_resourceRoot</code>, who's value is
	resolved <em>remotely</em> by the client browser.
</p>

<p>
	The template that is used for a given velocity-template rendering is
	given by the <code>elda:velocityTemplate</code> property of that
	renderer:
</p>

<pre>
... elda:velocityTemplate "some-template-name.vm"
</pre>

<p>
	If no <code>velocityTemplate</code> property is defined, Elda uses
	<code>"page-shell.vm"</code>.
</pre>

<h3>Other variables used by the stylesheets</h3>

<ul>
    <li>activeImageBase: the location within the
    resource root where the active (enabled) images
    used by the stylesheet are fetched from.
    </li>

    <li>inactiveImageBase: the location within the
    resource root where the inactive (disabled) images
    used by the stylesheet are fetched from.
    </li>

</ul>

<h3>Variables configuring rendering used by the Elda code</h3>


<ul>
    <li>_suppress_ipto: unless this variable is defined
    and has the value "yes", the meta-data (and hence the
    complete rendered model) for an item endpoint will
    include an <code>isPrimaryTopicOf</code> property
    of the selected item with value the currently displayed
    URI.    
    </li>

    <li>_suppress_media_type: If there is no .formatter
    suffix in the request URL, and no _format= query
    parameter, then the prescribed LDA behaviour is to
    see if the request headers specify an appropriate
    media type. If the requesting entity is a browser
    it almost always will (with */*), which is inconvenient
    when testing for the default default behaviour of
    sending JSON. Setting this variable to "yes" will
    cause Elda to ignore the supplied media type.
    </li>

    <li>_exceptionIfEmpty: by default, if a query for
    an item template returns no item (because the requested
    item has none of the required properties) Elda will
    generate a 404 response rather than displaying an
    empty item endpoint page. If the variable _exceptionIfEmpty
    does not have the value "<code>yes</code>", then the
    empty page is displayed.
    </li>
</ul>

<h2 id="wildcard-properties">Wildcard '*' in view property chains</h2>

<p>
    A property chain appearing in a view specification
    may contain the special element '*', meaning "any
    property". In the generated query it is replaced by
    a fresh variable. There can be any number of *-elements,
    anywhere within the chain.
</p>

<h2 id="uri-rewriting">URI rewriting</h2>

<p>
	(<em>This feature is experimental and its details
	may change.</em>)
</p>

<p>
	An Elda configuration may have rewrite rules associated
	with it. These rules are applied to the viewed resources
	before the model is supplied by the renderer. The intention
	is that during configuration development for applications
	where the SPARQL data contains URIs that correspond to
	application pages, the "official" URIs present in the
	data will be rewritten to "local" URIs which, when
	they are used as the target of an HTTP GET, will retrieve
	local data.
</p>

<p>
	All the URIs in the view model are rewritten, including
	the datatypes of typed literals. Lexical forms, language
	codes, and blank node IDs are not rewritten.
</p>

<p>
	The rewrite rules are specified by <code>elda:rewriteResultURIs</code>
	properties of the LDA config and apply to all (and only) endpoints
	of that config. There can be arbitrarily many such properties.
	The value(s) of the properties are resources (typically blank
	nodes) with the properties <code>elda:ifStarts</code> and
	<code>elda:replaceStartBy</code>, for example:
</p>

<pre>
... ; elda:rewriteResultURIs
	[ elda:ifStarts "http://education.data.gov.uk/"
	; elda:replaceStartBy "http://localhost:8080/elda/"
	]
</pre>

<p>
	URIs starting with the value of the <code>ifStarts</code>
	property are rewritten by replacing the <code>ifStarts</code>
	value with the <code>replaceStartBy</code> value, so
	given the rewrite rule above,
</p>

<pre>
http://education.data.gov.uk/doc/school
</pre>

<p>
	will be rewritten to
</p>

<pre>
http://localhost:8080/elda/doc/school
</pre>

<p>
	If multiple <code>ifStarts</code> values match, the
	longest is preferred. It is an error for multiple
	rules to share an <code>ifStarts</code> value.
</p>

<h2 id="describe-all-label"><code>elda:describeAllLabel</code></h2>

<p>
    If a new viewer is declared with the property
    <code>elda:describeAllLabel</code>, it becomes a
    variant of the <code>describeAllViewer</code>
    where the label property used is the object of
    that property rather than <code>rdfs:label</code>.
</p>

<h2 id="allow-reserved"><code>elda:allowedReserved</code></h2>

<p>
    Normally (and as prescribed by the spec) Elda will
    generate a 400 status for queries that try and use
    unknown reserved parameter names (those beginning
    with _), eg <code>?_example=17</code>.
</p>

<p>
    The property <code>elda:allowReserved</code> may be
    attached to an API or to an endpoint. Its values
    are the names of reserved parameters that should be
    ignored rather than generating status 400.
</p>

<p>
    Attachments to the API apply to all endpoints; attachments
	to one endpoint affect only that endpoint. Elda automatically
	makes the parameter name "_" allowed, since it is often used
	in JASONP queries.
</p>

<h2 id="etags">Etag generation</h2>

<p>
    If an endpoint has the property <code>elda:enableETags</code>
    with value <code>true</code>, or it does not have that
    property but its parent API spec does with value
    <code>true</code>, then Elda will generate an etag
    on successful responses. The value of the etag is derived
    from hashes of:
</p>

<ul>
    <li>the request URI</li>
    <li>the Accept header (if present)</li>
    <li>the Accept-Encoding header (if present)</li>
    <li>the response's media type</li>
    <li>the content of the model</li>
</ul>

<h2 id="item-template-fallback">Item template fallback</h2>

<p>
    If an inbound URI does not match any of the uriTemplates
    of the endpoints, Elda attempts to match that URI against
    any item templates of the endpoints. If it finds a match,
    then the query is redirected to that item endpoint.
</p>

<p>
    This behaviour is currently not configurable.
</p>

<h2 id="configuration-rendering">Configuration rendering</h2>

<p>
    Elda provides the api:base-relative URI path <code>/api-config</code>.
    Browsing this URI delivers a rendering of the various APIs that
    the Elda instance provides. Each API description shows the
    different endpoints, with their variable bindings and named views,
    and the dictionary of shortnames appropriate to this endpoint.
    By default the descriptions are hidden (for compactness) and
    are revealed by clicking on the section titles.
</p>

<p>
    The api:base-relative URI path
    <code>/meta/<span style='color: blue'>some/uri/template</span></code>
    provides the same configuration description as <code>/api-config</code>,
    but the API and endpoint for
    <span style='color: blue'>some/uri/template</span>
    are already opened.
</p>


<h1 id="formatting-extensions">Formatting extensions</h1>

<h2>Location of XSLT stylesheets</h2>

<p>
	If the object of an <code>api:stylesheet</code> directive starts
	with the prefix "xsl:", then the stylesheet is loaded from Elda's
	stylesheet directory, wherever that is. (By default it is
	<code>webapp/xsltsheets</code>, but this will become configurable.)
</p>

<h2>Java renderer factories</h2>

<p>
	If a formatter has the property
	<code>http://www.epimorphics.com/vocabularies/lda#className</code>,
	then the (String) object of that property must be the name of a Java
	class that implements the <code>RendererFactory</code> interface.
	When rendering is required, an instance of that class is invoked
	to deliver a Renderer, and that Renderer is used to render the
	result set.
</p>

<h2 id="atom-feed">The Atom renderer</h2>

<p>
	Elda contains an experimental atom-feed renderer. To use it, add
	a new formatter to the configuration file:
</p>

<pre>
...
; api:formatter
    [a elda:FeedFormatter
    ; api:name "atom"
    ; elda:className "com.epimorphics.lda.renderers.FeedRendererFactory"
    ; api:mimeType "application/atom+xml"
    ; elda:feedTitle "an example Elda feed"
    ]
</pre>

<p>
	The ID of the feed is the URI used to create it. The entries of the
	feed correspond to the selected items of the query; the ID of an
	entry is the URI of the corresponding item.
</p>

<p>
	The title of the feed is set using the elda:feedTitle
	property of the formatter in the LDA config, as in the example above.
	The title of an entry is set from the value of the first of the
	properties in the list
</p>

<pre>
<code>api:label</code>
<code>skos:prefLabel</code>
<code>rdfs:label</code>
</pre>

<p>
	that is defined; this list can be changed
	by setting the value of the formatter's <code>elda:feedLabelProperties</code> property.
</p>

<p>
	The update time of a feed is the latest of the updated
	times of its entries.
</p>

<p>
	The update time of an entry is the value of the first
	property in the list:
</p>

<pre>
dct:modified
dct:date
dct:dateAccepted
dct:dateSubmitted
dct:created
</pre>

<p>
	that is defined. This list can be changed by setting the value of the
	formatter's <code>elda:feedFateProperties</code> property.
</p>

<p>
	The content of an entry is similar to the XML rendering of the
	resource for this entry. Currently <strong>circularity checking is not
	available</strong>. The entry is given its own namespace, which defaults
	to the Elda namespace but can be set in the feed configuration using
	the property <code>elda:feedNamespace</code>.
</p>

<p>
	The rights of an entry is the value of the first property in the list
</p>

<pre>dct:rights</pre>

<p>
	that is defined; otherwise there is no rights element. This list can
	be changed by setting the value of the formatter's <code>elda:feedRightsProperties</code> property.
</p>

<p>
	The rights of a feed can be specified by giving a value to the
	<code>elda:feedRights</code> property of the formatter.
</p>

<p>
	The authors of a feed are specified by the list-valued property
	<code>elda:feedAuthors</code>. The authors of an entry are specified
	by the values of the first property in the list
</p>

<pre>
dct:creator
dct:contributor
</pre>

<p>
	That has any. This list can be changed by setting the value of the
	formatter's <code>elda:feedAuthorProperties</code>.
</p>

<h1 id="statistics">Statistics</h1>

<h2>HTML display of statistics</h2>

<p>
    The api:base-relative URI path <code>/control/show-stats</code> displays
    statistics about the queries that this Elda instance has handled, including:
</p>

<ul>
    <li>the total number of requests made</li>
    <li>the number of requests that failed</li>
    <li>the number of selection cache hits</li>
    <li>the number of view cache hits</li>
</ul>

<p>
    (Elda maintains two internal caches, one mapping the computed selection
    query to the list of items it generates, the other mapping (list of
    item, view) pairs to generated result sets. These are independant of
    any caches provided by <em>eg</em> an Apache server wrapping Elda.)
</p>

<ul>
    <li>the elapsed time dealing with all requests</li>
    <li>the elapsed time taken for item-selection queries</li>
    <li>the elapsed time taken for view-display queries</li>
    <li>the elapsed time taken to render an Elda result</li>
    <li>any remaining non-query non-rendering time</li>
</ul>

<p>
    All of these results show the total time, the mean time over all
    requests, and the maximum and minimum times over all requests.
</p>

<ul>
    <li>the size of the rendered results</li>
    <li>the size of the select queries</li>
    <li>the size of the view queries</li>
</ul>

<p>
    All of these results show the total size (in [kilo-]bytes),
    and the mean, maximum, and minimum over all requests.
</p>

<p>
    The display also breaks down rendering sizes and times by
    the rendering format (ie JSON/XML/HTML ...).
</p>

<h2>JMX statistics</h2>

<p>
	Elda can also serve limited JMX statistics (the same ones as are
	accessible using <code>show-stats</code>) by enabling the appropriate
	listeners in web.xml:
</p>

<pre>
&lt;listener>
  &lt;listener-class>com.epimorphics.lda.jmx.Statistics&lt;/listener-class>
  &lt;listener-class>com.epimorphics.lda.jmx.CacheControl&lt;/listener-class>
&lt;/listener>
</pre>

<p>
	This feature is experimental; it may be dropped in a future release.
</p>

<h2 id="cache">Cache</h2>

<p>
	Elda caches the results of queries so that they may be re-served
	quickly. When the cache gets "too full", it is reset. "Too full"
	by default is measured by the number of triples in the cache;
	the default limit is 20000 triples.
</p>

<p>
	The cache policy can be changed by setting the property
	<code>elda:cachePolicyName</code> to a string of the
	form <code>"name:integer"</code> where <code>name</code>
	is the name of a policy, eg <strong>default</strong>, and the optional
	<code>:integer</code> gives an associated limit.
</p>

<p>
The available cache policies are
</p>
<ul>
  <li><code>default</code> &mdash; same as limit-triples.</li>

  <li><code>limit-triples</code> &mdash; clear the cache when
    the number of triples retained is greater than the limit.
  </li>

  <li><code>limit-entries</code> &mdash; clear the cache when
    the number of entries is greater than the limit.
  </li>

  <li><code>perma-cache</code> &mdash; keep everything
    (not a good choice in production).
  </li>
</ul>

<p>
	Cache policies can be attached to the API spec and over-ridden
	on individual endpoints.
</p>

<h3>external control of the Elda cache</h3>

<p>
If a request to Elda has a <code>pragma</code> or <code>cache-control:</code> header
with value <code>no-cache</code> (such as a CRTL/F5 refresh might
cause on Firefox) then that request is not served from the cache.
The resulting response is then cached.
</p>

<p>
The Elda-webapp-relative URL <code>control/show-cache</code> shows information
about the Elda cache state and provides two buttons: one to reset
the statistics count, and another to clear the Elda cache completely.
(The latter is exactly equivalent to POSTing to <code>control/clear-cache</code>.)
</p>

<h1>Shortnames in Elda</h1>

<h2 id="shortname-restrictions">Restrictions on shortname selection</h2>

<p>
    In an (E)lda configuration file, the configurer may define
    "short names" for properties and resources. However, the
    current supplied example XSLT stylesheets expect that the
    properties used to define the metadata about a query and
    its results have certain specified shortnames.
</p>

<p>
    Elda reserves and predefines those shortnames; the configuation
    writer should not attempt to define them themselves.
</p>

<p>
    The reserved names are the local names (except where otherwise
    indicated) of the properties:
</p>

<table class="table table-striped table-condensed">
	<thead> <tr><th>prefix</th> <th>term</th> <th>term</th> <th>term</th></tr></thead>
	<tr> <td>rdf</td>  <td>type</td> <td>value</td> <td>&nbsp;</td> </tr>
	<tr> <td>rdfs</td>  <td>label</td> <td>comment</td> <td>&nbsp;</td> </tr>

	<tr> <td>xsd</td>  <td>integer</td> <td>decimal</td> <td>string</td> </tr>
	<tr> <td>xsd</td>  <td>boolean</td> <td>int</td> <td>short</td> </tr>
	<tr> <td>xsd</td>  <td>byte</td> <td>long</td> <td>double</td> </tr>
	<tr> <td>xsd</td>  <td>date</td> <td>time</td> <td>&nbsp;</td> </tr>

	<tr> <td>doap</td>  <td>implements</td> <td>releaseOf</td> <td>homepage</td> </tr>
	<tr> <td>doap</td>  <td>repository</td> <td>browse</td> <td>location</td> </tr>
	<tr> <td>doap</td>  <td>wiki</td> <td>revision</td> <td>&nbsp;</td> </tr>
	<tr> <td>doap</td>
		<td>bug-database <div>(as bug_database)</div></td>
		<td>programming-language <div>(as programming_language)</div></td>
		<td>&nbsp;</td>
	</tr>

	<tr> <td>opmv</td>  <td>software</td> <td>&nbsp;</td> <td>&nbsp;</td> </tr>

	<tr> <td>api</td>  <td>definition</td> <td>extendedMetadataVersion</td> <td>page</td> </tr>
	<tr> <td>api</td>  <td>items</td> <td>item</td> <td>processor</td> </tr>
	<tr> <td>api</td>  <td>property</td> <td>selectionResult</td> <td>termBinding</td> </tr>
	<tr> <td>api</td>  <td>variableBinding</td> <td>viewingResult</td> <td>wasResultOf</td> </tr>
	<tr> <td>dct</td>  <td>format</td> <td>hasFormat</td> <td>hasPart</td> </tr>
	<tr> <td>dct</td>  <td>hasVersion</td> <td>isFormatOf</td> <td>isPartOf</td> </tr>
	<tr> <td>dct</td>  <td>isVersionOf</td> <td>&nbsp;</td> <td>&nbsp;</td> </tr>
	<tr> <td>elda</td>  <td>listURL</td> <td>sparqlQuery</td> <td>&nbsp;</td> </tr>
	<tr> <td>foaf</td>  <td>isPrimaryTopicOf</td> <td>primaryTopic</td> <td>&nbsp;</td> </tr>
	<tr> <td>OpenSearch</td>  <td>itemsPerPage </td> <td>startIndex</td> <td>&nbsp;</td> </tr>
	<tr> <td>sparql</td>  <td>endpoint</td> <td>query</td> <td>url</td> </tr>
	<tr> <td>xhv</td>  <td>first</td> <td>next</td> <td>prev</td> </tr>

</table>

<h2 id="shortname-mode">Elda shortname creation</h2>

<p>
	When Elda renders a result-set graph using JSON or XML (and
	consequently HTML), URIs used as predicates are given short
	names if they have not been given in the configuration.
	Where possible these names should satisfy the shortname
	grammar; this allows them to be used as XML element names.
	Elda splits the URI into its <em>namespace</em> and
	<em>local name</em> parts and uses the localname as the
	basis for the generated shortname.
</p>

<p>
	<em>NOTE</em>. Elda uses the Jena XML-derived rule to
	split URIs, defining the local name as being the longest
	possible NCName that is a suffix of the URI. That name
	is not necessarily the same as that after a '#' or
	final '/' of a URI. Because the local name is an NCName
	it is automatically a legal XML element name.
</p>

<p>
	Elda has three <em>shortname modes</em> for generating
	shortnames. The mode for a given format may be
	specified by setting the property <code>elda:shortnameMode</code>
	on a declared <code>formatter</code> of the configuration
	to one of the values <code>elda:roundTrip</code>,
	<code>elda:preferLocalname</code>, or
	<code>elda:preferPrefixes</code>. The default for
	all renderers is <code>preferLocalname</code>.
</p>

<p>
	Elda follows these rules for converting a URI
	(not already given a shortname) with namespace N
	and local name L into a shortname:
</p>

<ol>
	<li>
		if the mode is <code>preferLocalname</code>,
		and this is the only URI with this local name,
		and L is not already a shortname,
		its shortname is L.
	</li>

	<li>
		if the namespace has an available prefix P
		and P_L is not already a shortname, then
		its shortname is P_L.
	</li>

	<li>
		if mode is not <code>roundTrip</code>, the
		shortname is L_N, where N is a (weak) hash
		of the namespace.
	</li>

	<li>
		otherwise the shortname is a reversible
		encoding of the full URI into a shortname
		(that is not short).
	</li>
</ol>

<p>
	The bindings of short names to full URIs &mdash;
	the <em>term bindings</em> &mdash; are made available
	as metadata in the rendered result. This metadata
	is by default only generated for HTML renderings;
	to have it present in JSON, XML, or RDF renderers,
	specify the query parameter <code>_metadata=bindings</code>
	or <code>_metadata=all</code> on the LDA request.
</p>



<h1 id="using-elda-from-java">Using Elda directly</h1>

<p>You don't need to go through a servlet (or restlet)
framework to exploit Elda. You can call the components
yourself and supply whatever glue you like. Note however
that details of the code structure may change between releases.
</p>

<h2>Creating an APISpec</h2>

<p>
The constructor
</p>
<pre>
APISpec(FileManager fm, Resource config, ModelLoader forVocab)
</pre>
<p>
delivers a new APISpec object configured from the given
Resource. You may have chosen a Resource with a known
URI in a config model, or found one with <code>rdf:type</code>
<code>api:API</code>, depending on your usecase. The
<code>ModelLoader</code> is only used if the config has
<code>api:vocabulary</code> elements, in which case it
loads the models for its API vocabulary. The <code>FileManager</code>
is used for accessing data sources.
</p>

<p>
Given an APISpec, the method <code>getEndpoints()</code>
delivers a list of <code>APIEndpoint</code> objects corresponding
(in no defined order) with the endpoint descriptions in the
config model.
</p>

<h2>Running an endpoint</h2>

<p>
You can then invoke
</p>
<pre>
APIEndpointUtil.call(APIEndpoint.Request r, Match match, String contextPath, MultiMap&lt;String, String&gt; queryParams)
</pre>
<p>
where
</p>

<ul>
  <li><em>r</em> is a Request object describing this LDA request. A
	Request itself contains:
	  <ul>
		<li>a Controls object for timing information</li>
		<li>the request URI</li>
		<li>bindings of LDA variables to values</li>
		<li>the shortname creation mode</li>
		<li>the name of the rendering format</li>
	  </ul>
  </li>

  <li><em>Match match</em> wraps the endpoint object and the variable bindings that
    made when matching the endpoint's <code>api:uriTemplate</code> against the
    request URI. The usual way to get a Match object is to call <code>getMatch</code>
    on a suitable <code>Router</code> value.
  </li>

  <li><em>URI requestURI</em> is the request URI for this request.
  </li>

  <li><em>contextPath</em> is the context path to assume (it is written into the
	variable bindings)
  </li>

  <li><em>MultiMap queryParams</em> is a map from query parameter names to their
    (string) values.
  </li>

</ul>

<p>
The call returns a three-element object which contains the
<code>ResultSet</code> of the query execution (the result
model and selected items), a map (the <em>term bindings</em>
from shortnames to their URIs as appropriate for this resultset,
and the (updated) variable Bindings.
</p>

<h2>Rendering results</h2>

<p>
Once you have chosen a renderer <code>R</code> to use for the
result set, the invocation
</p>

<pre>
R.render( t, rc, termBindings, results )
</pre>

<p>
where <code>t</code> is a <code>Times</code> object,
delivers a String which is the rendering of <code>results</code>
according to the RenderContext <code>rc</code>, which you can
construct from the <code>VarValues</code> embedded in the call
context, the context path, and an AsURL object to convert URI
fragments into full URIs. The termBindings should be the
map returned from <code>APIEndpointUtil.call</code>.
</p>

<p>
The method call <code>R.getMediaType()</code> returns the media
type for the renderer's result.
</p>


<h1 id="building-elda">Building Elda</h1>

<p>
  Prerequisites:
  <a href="http://java.com/">Java</a> (underlying platform),
  <a href="http://mercurial.selenic.com/">Mercurial</a> (to fetch the sources),
  <a href="http://maven.apache.org/Maven">Maven</a> (build management).
  Maven will download remaining necessary jars for Jena, Jersey, etc.
</p>

<p>
  Download the Elda sources:
</p>

<pre>
hg clone https://elda.googlecode.com/hg/ elda
</pre>

<p>
places the Elda sources in ./elda (which is created if necessary).
</p>

<p>
Running
</p>

<pre>
mvn clean install
</pre>
<p>
will now build the Elda jars and put them into your local
Maven repository, along with all the jars that they depend
on. You can then either use Maven to build your own
application with those jars as dependencies, or extract
them and embed them in your own libraries.
</p>

<p>
Look in the (automatically created) file
<code>/lda/src/main/java/com/epimorphics/lda/Version.java</code>
to see which version of Elda is being built. If you want to use
a non-SNAPSHOT version, use
</p>
<pre>
hg update -r REVISION
</pre>

<p>
before running maven, where REVISION is your choice of the revision
tags you get from running:
</p>
<pre>
hg tags
</pre>

<p>
and selecting a tag that looks like <code>elda-1.X.Y</code>;
that is the shape of tag generated by the Elda release process.
</p>

<p>
As of Elda 1.2.23, the names of Elda modules (and the names of
the corresponding directories in the Elda sources) have changed.
</p>

<h1 id="accepted-content-types">Accepted content types</h1>

<p>
Elda accepts the following content types by default.
</p>

<ul>
    <li>text/javascript, application/javascript:
        for JSONP on some browsers.
    </li>
    <li>text/plain:
        Plain text JSON.
    </li>
    <li>application/rdf+xml, text/turtle:
        RDF/XML or Turtle representations of models.
    </li>
    <li>application/json: model rendered as JSON.
    </li>
    <li>text/xml, application/xml:
		model rendered as XML with whichever content type was
		asked for. (The renderings are identical.)
    </li>
    <li>text/html:
        model rendered by stylesheet applied to XML rendering.
    </li>
</ul>


<div class="footer">
<hr>
&copy; Copyright 2011&ndash;2013 Epimorphics Limited. For licencing conditions see
<a href="http://elda.googlecode.com/hg/LICENCE.html">http://elda.googlecode.com/hg/LICENCE.html</a>.
</div>
</div>

</div><!-- .container -->
</body>
</html>

